/*
 * Copyright (c) 1994, 2010, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.io;

/**
 * 此类是过滤输出流的所有类的超类。这些流位于现有输出流（<i>基础</i>输出流）之上，
 * 后者用作其基本数据接收器，但可能沿途转换数据或提供附加功能。
 * <p>
 * 类 <code>FilterOutputStream</code> 本身只是简单地覆盖了所有 <code>OutputStream</code> 的方法，
 * 使其版本将所有请求传递给基础输出流。 <code>FilterOutputStream</code> 的子类可以进一步覆盖这些方法中的某些方法，
 * 也可以提供额外的方法和字段。
 *
 * @author  Jonathan Payne
 * @since   JDK1.0
 */
public
class FilterOutputStream extends OutputStream {
    /**
     * 要过滤的基础输出流。
     */
    protected OutputStream out;

    /**
     * 创建一个输出流过滤器，建立在指定的基础输出流之上。
     *
     * @param   out   基础输出流。
     */
    public FilterOutputStream(OutputStream out) {
        this.out = out;
    }

    /**
     * 将指定的 <code>byte</code> 写入此输出流。
     * <p>
     * <code>write</code> 的合约是，将一个参数写入输出流。
     * 要写入的字节是参数 <code>b</code> 的八个低位。<br>
     * 参数 <code>b</code> 的 24 个高位将被忽略。
     * <p>
     * 子类 <code>FilterOutputStream</code> 必须提供此方法的实现。
     *
     * @param      b   要写入的 <code>byte</code>。
     * @exception  IOException  如果发生 I/O 错误。
     * @see        java.io.FilterOutputStream#out
     */
    public void write(int b) throws IOException {
        out.write(b);
    }

    /**
     * 将指定的字节数组写入此输出流。
     * <p>
     * <code>write(b)</code> 的合约是，应该与调用 <code>write(b, 0, b.length)</code>
     * 的效果完全相同。
     *
     * @param      b   要写入的数据。
     * @exception  IOException  如果发生 I/O 错误。
     * @see        java.io.FilterOutputStream#write(byte[], int, int)
     */
    public void write(byte b[]) throws IOException {
        write(b, 0, b.length);
    }

    /**
     * 从指定的字节数组写入 <code>len</code> 字节，从偏移量 <code>off</code> 开始，
     * 到此输出流。
     * <p>
     * <code>write(b, off, len)</code> 的合约是，将数组 <code>b</code> 中的某些字节按顺序写入输出流；
     * 元素 <code>b[off]</code> 是写入的第一个字节，<code>b[off+len-1]</code> 是写入的最后一个字节。
     * <p>
     * 子类 <code>FilterOutputStream</code> 的合约是，方法 <code>write(b, off, len)</code> 的
     * 实现必须读取输入，直到达到所需数量的输入数据为止。
     * 它应该尝试读取尽可能多的数据，但可能读取少于所需的数量。
     * 如果 <code>len</code> 为零，则不写入任何字节；否则，尝试写入至少一个字节。
     * <p>
     * 此方法为类 <code>FilterOutputStream</code> 提供了其合约的实现。
     * <p>
     * 此方法只是执行 <code>out.write(b, off, len)</code>。
     *
     * @param      b     数据。
     * @param      off   数据中的起始偏移量。
     * @param      len   要写入的字节数。
     * @exception  IOException  如果发生 I/O 错误。
     * @see        java.io.FilterOutputStream#out
     */
    public void write(byte b[], int off, int len) throws IOException {
        if ((off | len | (b.length - (len + off)) | (off + len)) < 0)
            throw new IndexOutOfBoundsException();

        for (int i = 0 ; i < len ; i++) {
            write(b[off + i]);
        }
    }

    /**
     * 刷新此输出流并强制写出任何缓冲的输出字节。
     * <p>
     * <code>flush</code> 的合约是，调用它表示，如果先前写入的任何字节已由输出流的实现缓冲，
     * 则应立即将这些字节写入其预期目标。
     * <p>
     * 如果预期目标是此基础输出流之一，则调用其 <code>flush</code> 方法。
     * <p>
     * 类 <code>FilterOutputStream</code> 的合约是，方法 <code>flush</code> 的
     * 实现只是执行 <code>out.flush()</code>。
     *
     * @exception  IOException  如果发生 I/O 错误。
     * @see        java.io.FilterOutputStream#out
     */
    public void flush() throws IOException {
        out.flush();
    }

    /**
     * 关闭此输出流并释放与该流关联的任何系统资源。
     * <p>
     * <code>close</code> 的合约是，关闭输出流。如果输出流已关闭，则 <code>close</code> 方法将不执行任何操作。
     * <p>
     * 类 <code>FilterOutputStream</code> 的合约是，方法 <code>close</code> 的
     * 实现只是执行 <code>out.close()</code>。
     *
     * @exception  IOException  如果发生 I/O 错误。
     * @see        java.io.FilterOutputStream#out
     */
    public void close() throws IOException {
        try {
            flush();
        } catch (IOException ignored) {
        }
        out.close();
    }
}
